.TH pyang 1 "Dec 7, 2008" "pyang version 0.9.3"
.SH NAME
pyang \- validate and convert YANG modules to various formats
.SH SYNOPSIS
.B pyang
[
.B "-hv"
] [
.B "--canonical"
] [
.BI "-o " name
] [
.BI "-f " format
] [
.BI "-p " path
] [
.BI "-W " what
]
.I "module..."


Only the most common options are listed here.  See below for a
complete list of options.
.SH DESCRIPTION
The \fBpyang\fP program is used to validate YANG modules.  It is also
used to convert YANG modules into equivalent YIN modules.  From a
valid module, a W3C XML Schema (XSD) or conceptual tree schema (RELAX
NG with additional annotations) can be generated.

If no \fIformat\fP is given, the specified modules are validated, and
the program exits with exit code 0 if all modules are valid.
.SH OPTIONS
.TP
.B "-h, --help"
Print a short help text and exit.
.TP
.B "-e, --list-errors"
Print a listing of all error codes and messages pyang might generate,
and then exit.
.TP
.B "--print-error-code"
On errors, print the symbolic error code instead of the error message.
.TP
.B "-Werror"
Treat warnings as errors.
.TP
.B "-Wnone"
Do not print any warnings.
.TP
.B "--canonical"
Validate the module(s) according to the canonical YANG order.
.TP
.BI "-f " format ", --format " format
Convert the module into \fIformat\fP.  When this parameter is present,
a single module must be given.  If no \fIoutput\fP file is specified,
the result is printed on stdout.  The supported formats are listed in
OUTPUT FORMATS below.
.TP
.BI "-o " outfile ", --output " outfile
Write the output to the file \fIoutfile\fP instead of stdout.
.TP
.BI "-p " path ", --path " path
\fIpath\fP is a colon (:) separated list of directories to search for
imported modules.  The following directories are always added to the
search path:

  1.  current directory
  2.  $YANG_MODPATH
  3.  $HOME/yang/modules
  4.  $YANG_INSTALL/yang/modules
      OR if $YANG_INSTALL is unset
      <the default installation directory>/yang/modules
      (on Unix systems: /usr/share/yang/modules)
.TP
.BI "--plugindir " plugindir
Load all YANG plugins found in the directory \fIplugindir\fR.  This
option may be given multiple times.  The following directories are
always added to the load path:

  1.  pyang/plugins from where pyang is installed
  2.  $PYANG_PLUGINPATH

.TP
.B "-d, --debug"
Turn on debugging of the pyang code.
.TP
.I module...
These are the names of the files containing the modules to be
validated, or the module to be converted.
.SH OUTPUT FORMATS
If pyang plugins are installed, these plugins may define their own
options, or add new formats to the \fI-f\fR option.  These options and
formats are listed in \fIpyang -h\fP.
.TP 12
\fIyin\fR
the XML syntax of YANG
.TP 
\fIyang\fR
.TP
\fIcts\fR
Conceptual tree schema (RELAX NG with annotations)
.TP
\fIxsd\fR
W3C XML Schema
.TP
\fIdepend\fR 
Prints a Makefile dependency rule for the module
.TP
\fItree\fR
tree structure of the module
.SH YANG OUTPUT
Options for the \fIyang\fR output format.
.TP
.B "--yang-canonical"
Generate all statements in the canonical order.
.SH YIN OUTPUT
Options for the \fIyin\fR output format.
.TP
.B "--yin-canonical"
Generate all statements in the canonical order.
.TP
.B "--yin-pretty-strings"
Pretty print strings, i.e. print with extra whitespace in the string.
This is not strictly correct, since the whitespace is significant
within the strings in XML, but the output is more readable.
.SH CTS OUTPUT
Options for the \fIcts\fR output format.
.TP
.B "--cts-no-documentation"
Do not print documentation annotations
.TP
.B "--cts-no-dublin-core"
Do not print Dublin Core metadata terms
.TP
.B "--cts-record-defs"
Record translations of all top-level typedefs and groupings in the
output schema, even if they are not used. This is useful for
translating library modules.
.SH XSD OUTPUT
Options for the \fIxsd\fR output format.
.TP
.B "--xsd-no-appinfo"
Do not print YANG specific appie.nfo
.TP
.B "--xsd-no-lecture"
Do not print the lecture about how the XSD can be used.
.TP
.B "--xsd-no-imports"
Do not generate xs:import elements.
.TP
.B "--xsd-no-includes"
Do not generate xs:include elements.
.TP
.B "--xsd-break-pattern"
Break long patterns so that they fit into RFCs. The resulting patterns
might not always be valid XSD, so use with care.
.SH DEPEND OUTPUT
The \fIdepend\fR output generates a Makefile dependency rule for files
based on a YANG module.  This is useful if files are generated from
the module.  For example, suppose a .c file is generated from each
YANG module.  If the YANG module imports other modules, or includes
submodules, the .c file needs to be regenerated if any of the imported
or included modules change.  Such a dependency rule can be generated
like this:

.nf
  $ pyang -f depend --depend-target mymod.c
      --depend-extension .yang mymod.yang
  mymod.c : ietf-yang-types.yang my-types.yang
.fi

Options for the \fIdepend\fR output format.
.TP
.B "--depend-target"
Makefile rule target.  Default is the modulename.
.TP
.B "--depend-no-submodules"
Do not generate dependencies for included submodules.
.TP
.B "--depend-extension"
YANG module file name extension.  Default is no extension.
.SH Example
The following example validates the standard YANG modules with derived
types:

.nf
  $ pyang ietf-yang-types.yang ietf-inet-types.yang
.fi

The following example converts the ietf-yang-types module into YIN:

.nf
  $ pyang -f yin -o ietf-yang-types.yin ietf-yang-types.yang
.fi
.SH ENVIRONMENT VARIABLES
pyang searches for referred modules in the colon (:) separated path
defined by the environment variable YANG_MODPATH and in the
directory $YANG_INSTALL/yang/modules.

pyang searches for plugins in the colon (:) separated path defined by
the environment variable PYANG_PLUGINDIR.
.SH BUGS
The XPath arguments for the \fBmust\fP and \fBwhen\fP statements are
checked only for basic syntax errors.
.SH Authors
Martin Bjorklund, Tail-f Systems, <mbj@tail-f.com>
.br
Ladislav Lhotka, CESNET, <lhotka@cesnet.cz>


